Nancy Smith
November 1974

				FAIL

There are 3 versions of FAIL at SUMEX:

1)  AIFAIL is an unmodified version of FAIL from the Stanford AI Lab.
    It is not the latest version and thus corresponds to the 1970
    FAIL manual by P.M. Petit which is available on-line as 
    <DOC>FAIL.MANUAL rather than to the more recent 1974 FAIL manual
    from the AI Lab by Wright & Gorin.
    This version of FAIL does not run well under TENEX but may have its
    uses for assembling certain old programs.

2)  FAIL is the version of FAIL that was TENEXized at BBN.

3)  IFAIL is a version of FAIL from the AI Lab which has been
    modified at IMSSS to fix up the areas that were
    dependent on the AI Lab system rather than the standard
    DEC system, but IFAIL is not TENEXized.

	In addition to the FAIL manual which is available on-line,
the following description of FAIL and IFAIL written by Robert Smith 
at IMSSS should be helpful:


		PROGRAM DOCUMENTATION

Title
PROGRAM NAME: FAIL	--symbolic assembler

Actual names in use:  FAIL, IFAIL

Maintenance;	(no one, see system staff)

general description: Main symbolic assembler.
	Supplants MACRO-X for most applications; faster,
	one-pass, block structured.
	translates a program from sybolic assembly
	language into machine language; actual output
	is relocatable binary file suitable for the
	LOADER (q.v.)
	source program must be prepared prior to using
       FAIL--  see any of the editors for how to prepare
	a text file.

Basic operation:
 Load program:	Type FAIL to the tenex exec
	FAIL responds with an asterisk when ready
 Specify operation: Type NAME2←NAME1/CR/
	where NAME1 is the name of the file on which
	your source text resides.
	NAME2 is the name of the file which FAIL will
	use for ouput. FAIL automatically adds an
	extension of .REL to NAME2.
	NAME2 will usually be the same as NAME1.
End of processing:
	if compilation is successful, FAIL will respond
	with an asterisk. NAME2.REL will contain the 
	output of the translation: see LOADER documentation
	to proceed.


FAIL p2

Additional comments:
	if the source program is on more than one file, they
	are given separated by commas, as NAME2←NAME1a,
	NAME1b, NAME1c
	IFAIL will accept a single NAME1/CR/ as equivalent
	to NAME1←NAME1 /CR/
	IF NAME2 is missing (but still have left arrow),
	no output file will be produced. This can be handy
	if you are fairly sure the program will not compile
	correctly and just want to check for error messages.
	if a source file is not found, FAIL will look for 
	a file with that name and the extension /FAI
	FAIL runs using the emulator. Therefore, file names
	are limited to 6 characters with a three character
	extension. Also, a new .REL (output) file is created
	each time the assembler is run. These will pile up
	on your directory, and must be removed by you.
	The program DELVER will remove all but the last 
	version, or you may delete by hand, or the following
	will also work: DELETE NAME2.REL;D then UNDELETE
	NAME2.REL to get back the latest version; then 
	EXPUNGE.
	Directory specs must be given after the file name
	in sguare brackets with commas; thus, [sys,tem].

Characteristics or different versions:
IFAIL;	Old FAIL, as used here before Tenex. Recognizes HISEG
	and LVAR pseudo-ops. Has short-form command
	(see above), prints page numbers every two seconds
	during compilation, prints file name when a new
	file is started. Does not know Tenex JSYS mnemonics;
	assemble file sys: TENEX.FAI ??????of your program.
FAIL:	A newer version, from BBN. Knows about all the
	standard JYSYS's, but does not have HISEG and LVAR		
	or short form commands.


MINI-MANUAL:

Program begins with TITLE, next word is program name 
	program ends with END, next word is label specifying
	starting address.
Numbers are usually octal. Preceed number by = to specify
	it as decimal.
symbol definition is done with left-arrow.
	literals given in square brackets, and may extend 
	over several lines. A matching right bracket is 
	always necessary.
; stops the scan on a line, for comments. USE THEM!
Example:
TITLE TEST

A ← 1	; standard accumulator definitions
B ← 2
C ← 3
max ← = 10 ; try ten times	
 count:   0   ; a variable

start:	reset	;a jsys, at start of all programs
	setzm count	;zero counter
	hrroi  a,  [asciz /type anything/]
	psout		;type a message
	pbin		;read a character
	cain   a,  "Y"	;see if it is ascii Y
	jrst  win	;yes. 
	aos    b,  count;incrent count, into b
	caige  b,  max	;see if max is reached
	jrst   loop	;not yet

	hrroi   a, [ascii / loose/]
	psout
	haltf

win;	hrroi [ascii /win/]
	psout
	haltf
end start



Brief stylicstic comments:

FAIL input is essentially free-field, but the following
	convention is handy:
label:	instruction	ac, address	;comment
	tab		tab	s	tab	s
The instruction following a conditional skip should
generally be indented one space, to call attention
to its conditional nature. This is sepecially important
after subroutines and JSYS's , where the reader		
may not recognize the possibility of a skip. Note the
following;
	CAME	A, lim
	 jrst  done

	caie  ch,  "a"
	cain  ch,  "A"
	 jrst gotit


		erstr
		 jrst  ertn0
		 jrst  ertn2

Blank lines are free. Always use one following an absolute
transfer of control.

Use symbolic names for accumulators, even those referenced
absolutely by JSYS calls:

	A ← 1 B ← 2 C ← 3 system standard
	P for push down stack (pushj p, subr)

Do not mix symbol definition operations in with the code
stream, even though it will compile correctly.

bad←←	label:  movei a, 100
	   integer count	
		movem a count
Macros which generate more than one line of code must
be used sparingly if at all.